Data structures¶

Data structures for parsed JustWatch API responses.

Each response is parsed into a NamedTuple for easy access to each field and type checking. Each function available in this library is returning one (or more) of these structures.

Some of the returned fields are marked optional (with | None), as they might be missing from the API response. I tried to only mark fields as optional when they are actually optional, based on my own testing. However, if you need maximum safety you might need to treat all fields as optional, as there is no guarantee what the API will return.

CLASS	DESCRIPTION
`Episode`	Parsed data related to a single episode.
`Interactions`	Parsed data regarding number of likes and dislikes on JustWatch for a single entry.
`MediaEntry`	Parsed full details for a single entry.
`Offer`	Parsed single offer from JustWatch GraphQL API for a single entry.
`OfferPackage`	Parsed single offer package from one provider from JustWatch GraphQL API.
`Scoring`	Parsed data related to user scoring for a single entry.
`StreamingCharts`	Parsed data related to JustWatch rank for a single entry.

Episode ¶

Bases: NamedTuple

Parsed data related to a single episode.

It's a subset of fields available in MediaEntry.

ATTRIBUTE	DESCRIPTION
`episode_id`	Episode ID, contains type code and numeric ID. TYPE: `str`
`object_id`	Object ID, the numeric part of full episode ID. TYPE: `int`
`object_type`	Type of entry, for episodes should be `SHOW_EPISODE`. TYPE: `str`
`title`	Full title. TYPE: `str \| None`
`release_year`	Release year as a number. TYPE: `int \| None`
`release_date`	Full release date as a string, e.g. `2013-12-16`. TYPE: `str \| None`
`runtime_minutes`	Runtime in minutes. TYPE: `int \| None`
`short_description`	Short description of this episode. TYPE: `str \| None`
`episode_number`	Number of this episode. TYPE: `int \| None`
`season_number`	Season number with this episode. TYPE: `int \| None`
`offers`	List of available offers for this episode, empty if there are no available offers. TYPE: `list[Offer]`

Interactions ¶

Bases: NamedTuple

Parsed data regarding number of likes and dislikes on JustWatch for a single entry.

ATTRIBUTE	DESCRIPTION
`likes`	Number of likes on JustWatch. TYPE: `int \| None`
`dislikes`	Number of dislikes on JustWatch. TYPE: `int \| None`

MediaEntry ¶

Bases: NamedTuple

Parsed full details for a single entry.

Used by multiple functions in this library, e.g., details, search, seasons.

Some details might be specific for different media types, e.g. total_episode_count is only relevant for seasons, total_season_count for seasons and shows, etc. For non-relevant fields, the value is None.

ATTRIBUTE	DESCRIPTION
`entry_id`	Entry ID, contains type code and numeric ID. TYPE: `str`
`object_id`	Object ID, the numeric part of full entry ID. TYPE: `int`
`object_type`	Type of entry, e.g. `MOVIE`, `SHOW`. TYPE: `str`
`title`	Full title. TYPE: `str`
`url`	URL to JustWatch with details for this entry. TYPE: `str`
`release_year`	Release year as a number. TYPE: `int`
`release_date`	Full release date as a string, e.g. `2013-12-16`. TYPE: `str`
`runtime_minutes`	Runtime in minutes. TYPE: `int`
`short_description`	Short description of this entry. TYPE: `str`
`genres`	List of genre codes for this entry, e.g. `["rly"]`, `["cmy", "drm", "rma"]`. TYPE: `list[str]`
`imdb_id`	ID of this entry in IMDB. TYPE: `str \| None`
`tmdb_id`	ID of this entry in TMDB. TYPE: `str \| None`
`poster`	URL to poster for this ID. TYPE: `str \| None`
`backdrops`	List of URLs for backdrops (full screen images to use as background). TYPE: `list[str]`
`age_certification`	Age rating as a string, e.g.: `R`, `TV-14`. TYPE: `str \| None`
`scoring`	Scoring data. TYPE: `Scoring \| None`
`interactions`	Interactions (likes/dislikes) data. TYPE: `Interactions \| None`
`streaming_charts`	JustWatch charts/ranks data. TYPE: `StreamingCharts \| None`
`offers`	List of available offers for this entry, empty if there are no available offers. TYPE: `list[Offer]`
`total_season_count`	Total season count, for non-shows it's always `None`. TYPE: `int \| None`
`total_episode_count`	Total number of episodes in this season, for non-seasons it's always `None`. TYPE: `int \| None`
`season_number`	Number of this season, for movies it's always `None`. TYPE: `int \| None`
`episode_number`	Number of this episode, for non-episodes it's always `None`. TYPE: `int \| None`

Offer ¶

Bases: NamedTuple

Parsed single offer from JustWatch GraphQL API for a single entry.

One platform can have multiple offers for one entry available, e.g., renting, buying, streaming; each with different prices, etc.

ATTRIBUTE	DESCRIPTION
`id`	Offer ID. TYPE: `str`
`monetization_type`	Type of monetization of this offer, e.g. `FLATRATE` (streaming), `RENT`, `BUY`. TYPE: `str`
`presentation_type`	Quality of media in this offer, e.g. `HD`, `SD`, `4K`. TYPE: `str`
`price_string`	Current price as a string with currency, suitable for displaying to users. Format can change based on used `language` argument. TYPE: `str \| None`
`price_value`	Current price as a numeric value. TYPE: `float \| None`
`price_currency`	Represents only currency, without price, or value. TYPE: `str`
`last_change_retail_price_value`	Previous available price if change in price was recorded. TYPE: `float \| None`
`type`	Type of offer. TYPE: `str`
`package`	Information about platform on which this offer is available. TYPE: `OfferPackage`
`url`	URL to this offer. TYPE: `str`
`element_count`	Element count, usually `0`. TYPE: `int \| None`
`available_to`	Date until which this offer will be available. TYPE: `str \| None`
`deeplink_roku`	Deeplink to this offer in Roku. TYPE: `str \| None`
`subtitle_languages`	List of 2-letter language codes of available subtitles, e.g. `["en", "pt", "de"]`. TYPE: `list[str]`
`video_technology`	List of known video technologies available in this offer, e.g. `DOLBY_VISION`. TYPE: `list[str]`
`audio_technology`	List of known audio technologies available in this offer, e.g. `DOLBY_ATMOS`. TYPE: `list[str]`
`audio_languages`	List of 2-letter language codes of available audio tracks, e.g. `["en", "pt", "de"]`. TYPE: `list[str]`

OfferPackage ¶

Bases: NamedTuple

Parsed single offer package from one provider from JustWatch GraphQL API.

Contains information about platform (e.g., Netflix, Hulu) on which given offer is available. Also used by providers function to return data about all available providers.

ATTRIBUTE	DESCRIPTION
`id`	ID of the provider/platform for this offer. TYPE: `str`
`package_id`	Package ID. I'm not sure how it's different from regular `id`. TYPE: `int`
`name`	Name of the platform in format suited to display for users. TYPE: `str`
`technical_name`	Technical name of the platform, usually all lowercase with no whitespaces. TYPE: `str`
`short_name`	3-letter provider name. TYPE: `str`
`monetization_types`	List of monetization types available for this provider (e.g., `ADS`, `FLATRATE` (streaming), `RENT`). TYPE: `list[str]`
`icon`	Platform icon URL. TYPE: `str`

Scoring ¶

Bases: NamedTuple

Parsed data related to user scoring for a single entry.

ATTRIBUTE	DESCRIPTION
`imdb_score`	IMDB score. TYPE: `float \| None`
`imdb_votes`	Number of votes on IMDB. TYPE: `int \| None`
`tmdb_popularity`	TMDB popularity score. TYPE: `float \| None`
`tmdb_score`	TMDB score. TYPE: `float \| None`
`tomatometer`	Tomatometer score on Rotten Tomatoes. TYPE: `int \| None`
`certified_fresh`	Flag whether entry has "Certified Fresh" seal on Rotten Tomatoes. TYPE: `bool \| None`
`jw_rating`	JustWatch rating. TYPE: `float \| None`

StreamingCharts ¶

Bases: NamedTuple

Parsed data related to JustWatch rank for a single entry.

ATTRIBUTE	DESCRIPTION
`rank`	Rank on JustWatch. TYPE: `int`
`trend`	Trend in ranking on JustWatch, `UP`, `DOWN`, `STABLE`. TYPE: `str`
`trend_difference`	Difference in rank; related to trend. TYPE: `int`
`top_rank`	Top rank ever reached. TYPE: `int`
`days_in_top_3`	Number of days in top 3 ranks. TYPE: `int`
`days_in_top_10`	Number of days in top 10 ranks. TYPE: `int`
`days_in_top_100`	Number of days in top 100 ranks. TYPE: `int`
`days_in_top_1000`	Number of days in top 1000 ranks. TYPE: `int`
`updated`	Date when rank data was last updated as a string, e.g.: `2024-10-06T09:20:36.397Z`. TYPE: `str`